// 定义包路径，属于驾校相关的Web控制器
package com.ruoyi.web.controller.jiaxiao;

// 导入Java工具类
import java.util.List;
// 导入Spring框架相关注解和类
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;  // 用于文件上传
// 导入若依框架相关注解和工具类
import com.ruoyi.common.annotation.Log;  // 日志记录注解
import com.ruoyi.common.core.controller.BaseController;  // 基础控制器
import com.ruoyi.common.core.domain.AjaxResult;  // 接口返回结果封装类
import com.ruoyi.common.core.page.TableDataInfo;  // 分页数据封装类
import com.ruoyi.common.enums.BusinessType;  // 业务操作类型枚举
import com.ruoyi.common.utils.SecurityUtils;  // 安全工具类，用于获取当前用户信息
import com.ruoyi.common.utils.poi.ExcelUtil;  // Excel处理工具类
import com.ruoyi.framework.web.service.PermissionService;  // 权限服务类
import org.springframework.security.access.prepost.PreAuthorize;  // 方法级权限控制注解
// 导入学员相关的实体类和服务接口
import com.ruoyi.system.domain.JxStudent;  // 学员实体类
import com.ruoyi.system.service.IJxStudentService;  // 学员服务接口

/**
 * 驾校学员控制器
 * 处理与学员信息相关的HTTP请求
 */
@RestController  // 标识为REST风格控制器，返回结果自动转为JSON
@RequestMapping("/jiaxiao/student")  // 定义请求路径前缀，所有接口路径以此开头
public class JxStudentController extends BaseController {  // 继承基础控制器，获取分页等通用功能

    // 自动注入学员服务接口，用于调用业务逻辑层方法
    @Autowired
    private IJxStudentService jxStudentService;

    /**
     * 查询学员列表
     * @param query 包含查询条件的学员实体对象
     * @return 分页后的学员列表数据
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:list')")  // 权限控制，需有指定权限才能访问
    @GetMapping("/list")  // 处理GET请求，完整路径为/jiaxiao/student/list
    public TableDataInfo list(JxStudent query) {
        startPage();  // 开启分页，从请求参数中获取分页信息
        List<JxStudent> list = jxStudentService.selectJxStudentList(query);  // 调用服务层查询学员列表
        return getDataTable(list);  // 封装分页结果并返回
    }

    /**
     * 获取学员详细信息
     * @param studentId 学员ID
     * @return 包含学员详情的AjaxResult对象
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:query')")  // 权限控制
    @GetMapping(value = "/{studentId}")  // 处理GET请求，路径为/jiaxiao/student/{studentId}
    public AjaxResult getInfo(@PathVariable Long studentId) {  // @PathVariable获取路径中的学员ID
        return success(jxStudentService.selectJxStudentById(studentId));  // 调用服务层查询详情并返回成功结果
    }

    /**
     * 新增学员
     * @param entity 包含新增学员信息的实体对象
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:add')")  // 权限控制
    @Log(title = "学员", businessType = BusinessType.INSERT)  // 记录操作日志，操作类型为新增
    @PostMapping  // 处理POST请求，路径为/jiaxiao/student
    public AjaxResult add(@RequestBody JxStudent entity) {  // @RequestBody接收请求体中的JSON数据
        return toAjax(jxStudentService.insertJxStudent(entity));  // 调用服务层新增方法，返回操作结果
    }

    /**
     * 修改学员信息
     * @param entity 包含修改后学员信息的实体对象
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:edit')")  // 权限控制
    @Log(title = "学员", businessType = BusinessType.UPDATE)  // 记录操作日志，操作类型为更新
    @PutMapping  // 处理PUT请求，路径为/jiaxiao/student
    public AjaxResult edit(@RequestBody JxStudent entity) {  // 接收请求体中的JSON数据
        return toAjax(jxStudentService.updateJxStudent(entity));  // 调用服务层更新方法，返回操作结果
    }

    /**
     * 删除学员
     * @param studentIds 要删除的学员ID数组
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:remove')")  // 权限控制
    @Log(title = "学员", businessType = BusinessType.DELETE)  // 记录操作日志，操作类型为删除
    @DeleteMapping("/{studentIds}")  // 处理DELETE请求，路径为/jiaxiao/student/{studentIds}
    public AjaxResult remove(@PathVariable Long[] studentIds) {  // 获取路径中的ID数组
        return toAjax(jxStudentService.deleteJxStudentByIds(studentIds));  // 调用服务层批量删除方法
    }

    /**
     * 学员状态流转（变更学员状态）
     * @param studentId 学员ID
     * @param toStatus 目标状态
     * @param remark 变更备注（可选参数）
     * @return 操作结果（成功/失败）
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:edit')")  // 权限控制
    @Log(title = "学员状态变更", businessType = BusinessType.UPDATE)  // 记录状态变更日志
    @PutMapping("/changeStatus/{studentId}")  // 处理PUT请求，路径为/jiaxiao/student/changeStatus/{studentId}
    public AjaxResult changeStatus(@PathVariable Long studentId,
                                   @RequestParam String toStatus,
                                   @RequestParam(required = false) String remark) {
        String operator = SecurityUtils.getUsername();  // 获取当前操作人用户名
        // 调用服务层变更状态方法，返回操作结果
        return toAjax(jxStudentService.changeStatus(studentId, toStatus, operator, remark));
    }

    /**
     * 导出学员数据为Excel
     * @param query 导出数据的查询条件
     * @return 包含Excel文件的响应结果
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:export')")  // 权限控制
    @Log(title = "学员", businessType = BusinessType.EXPORT)  // 记录导出日志
    @PostMapping("/export")  // 处理POST请求，路径为/jiaxiao/student/export
    public AjaxResult export(JxStudent query) {
        List<JxStudent> list = jxStudentService.selectJxStudentList(query);  // 查询要导出的数据
        ExcelUtil<JxStudent> util = new ExcelUtil<>(JxStudent.class);  // 创建Excel工具类实例
        return util.exportExcel(list, "学员数据");  // 导出Excel并返回结果
    }

    /**
     * 导入学员数据（从Excel文件）
     * @param file 上传的Excel文件
     * @param updateSupport 是否支持更新（存在则更新，不存在则新增）
     * @return 导入结果信息
     * @throws Exception 处理过程中可能抛出的异常
     */
    @PreAuthorize("@ss.hasPermi('jiaxiao:student:import')")  // 权限控制
    @Log(title = "学员", businessType = BusinessType.IMPORT)  // 记录导入日志
    @PostMapping("/importData")  // 处理POST请求，路径为/jiaxiao/student/importData
    public AjaxResult importData(MultipartFile file, boolean updateSupport) throws Exception {
        ExcelUtil<JxStudent> util = new ExcelUtil<>(JxStudent.class);  // 创建Excel工具类实例
        List<JxStudent> list = util.importExcel(file.getInputStream());  // 从文件输入流中读取数据
        int success = 0;  // 记录成功导入的条数
        for (JxStudent s : list) {  // 遍历导入的数据列表
            if (updateSupport) {  // 如果支持更新
                jxStudentService.updateJxStudent(s);  // 执行更新操作
            } else {  // 不支持更新则执行新增
                jxStudentService.insertJxStudent(s);  // 执行新增操作
            }
            success++;  // 成功计数加1
        }
        return AjaxResult.success("导入成功" + success + "条");  // 返回导入结果
    }

    /**
     * 下载学员数据导入模板
     * @return 包含模板文件的响应结果
     */
    @PostMapping("/importTemplate")  // 处理POST请求，路径为/jiaxiao/student/importTemplate
    public AjaxResult importTemplate() {
        ExcelUtil<JxStudent> util = new ExcelUtil<>(JxStudent.class);  // 创建Excel工具类实例
        return util.importTemplateExcel("学员数据");  // 生成并返回导入模板
    }
}